package org.thinginitself.mixpath;



import org.jaxen.XPath;

import java.io.OutputStream;
import java.io.Writer;
import java.util.List;

/**
 * Extension to the Jaxen XPath interface. This supports adding and removing elements and attributes.
 * @author Andrew Harrison
 * @version 1.0.0 16/05/2011
 */
public interface MutableXPath extends XPath {

    /**
     * insert an Element as a child of the selected nodes
     * @param node the context node which is already contained in the document
     * @param name element name
     * @param selection  selected nodes to add the child nodes to
     * @return
     * @throws MiXPathException
     */
    public boolean insertElement(Object node, String name, List selection) throws MiXPathException;

    /**
     * insert an Element as a child of the selected nodes
     * @param node the context node which is already contained in the document
     * @param name element name
     * @param namespace the namespace of the element
     * @param selection  selected nodes to add the child nodes to
     * @return
     * @throws MiXPathException
     */
    public boolean insertElement(Object node, String name, String namespace, List selection) throws MiXPathException;

    /**
     * insert an Element as a child of the selected nodes
     * @param node the context node which is already contained in the document
     * @param name element name
     * @param namespace the namespace of the element
     * @param text text content for the element
     * @param selection  selected nodes to add the child nodes to
     * @return
     * @throws MiXPathException
     */
    public boolean insertElement(Object node, String name, String namespace, String text, List selection) throws MiXPathException;

    /**
     * Insert an attribute to the selected nodes
     * @param node
     * @param name
     * @param value
     * @param selection
     * @return
     * @throws MiXPathException
     */
    public boolean insertAttribute(Object node, String name, String value, List selection) throws MiXPathException;

    /**
     * insert an attribute to the selected nodes
     * @param node
     * @param name
     * @param namespace
     * @param value
     * @param selection
     * @return
     * @throws MiXPathException
     */
    public boolean insertAttribute(Object node, String name, String namespace, String value, List selection) throws MiXPathException;

    /**
     * insert text content into selected nodes
     * @param node
     * @param text
     * @param selection
     * @return
     * @throws MiXPathException
     */
    public boolean insertText(Object node, String text, List selection) throws MiXPathException;

    /**
     * remove an attribute from the selection with the given name and namespace
     * @param node
     * @param name
     * @param namespace
     * @param selection
     * @return
     * @throws MiXPathException
     */
    public boolean removeAttribute(Object node, String name, String namespace, List selection) throws MiXPathException;

    /**
     * remove an attribute from the selection with the given name
     * @param node
     * @param name
     * @param selection
     * @return
     * @throws MiXPathException
     */
    public boolean removeAttribute(Object node, String name, List selection) throws MiXPathException;

    /**
     * remove elements with the given name and namespace from the selection
     * @param node
     * @param name
     * @param namespace
     * @param selection
     * @return
     * @throws MiXPathException
     */
    public boolean removeElements(Object node, String name, String namespace, List selection) throws MiXPathException;

    /**
     * remove elements from the selection with the given name
     * @param node
     * @param name
     * @param selection
     * @return
     * @throws MiXPathException
     */
    public boolean removeElements(Object node, String name, List selection) throws MiXPathException;

    /**
     * remove the node object from the DOM
     * @param node
     * @return
     * @throws MiXPathException
     */
    public boolean removeElement(Object node) throws MiXPathException;

    /**
     * write the node to a stream
     * @param node
     * @param stream
     * @param options
     * @throws MiXPathException
     */
    public void writeTo(Object node, OutputStream stream, Options options) throws MiXPathException;

    /**
     * write the node to a writer
     * @param node
     * @param stream
     * @param options
     * @throws MiXPathException
     */
    public void writeTo(Object node, Writer stream, Options options) throws MiXPathException;
}
